<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<meta name="author" content="Aurelio Jargas www.aurelio.net">
<META NAME="generator" CONTENT="http://txt2tags.org">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
<LINK REL="stylesheet" TYPE="text/css" HREF="inc/site.css">
<TITLE>How to add a new target to txt2tags</TITLE>
<link rel="icon" type="image/png" href="/favicon.png">
</HEAD>
<BODY id="new-target">

<DIV CLASS="header" ID="header">
<H1>How to add a new target to txt2tags</H1>
<H3>It's easy!</H3>
</DIV>

<DIV CLASS="body" ID="body">
<div id="sidebar">
Hot
  <ul>
  <li id="menuonline"><a href="./online.php">Txt2tags Online</a></li>
  <li id="menumarkup"><a href="./markup.html">Markup Demo</a></li>
  </ul>
About
  <ul>
  <!-- <li id="menuhome"><a href="/">Home</a></li> -->
  <li id="menufeatures"><a href="./features.html">Features</a></li>
  <li id="menusample"><a href="./sample.html">Example</a></li>
  <li id="menushots"><a href="./shots.html">Screenshots</a></li>
  <li id="menudocs"><a href="./docs.html">Documentation</a></li>
  <li id="menutips"><a href="./tips.html">Tips &amp; Tricks</a></li>
<!--
  <li id="menuoldnews"><a href="./misc/oldnews.html">Old News</a></li>
<span style="font-weight:bold;color:red">--></span>
  </ul>
Code
  <ul>
  <li id="menudownload"><a href="./download.html">Download</a></li>
  <li id="menuchangelog"><a href="./changelog.html">Changelog</a></li>
  <li id="menutools"><a href="./tools.html">Tools</a></li>
  <li><a href="http://bugs.txt2tags.org">Bug tracker</a></li>
  <li><a href="http://svn.txt2tags.org">SVN</a></li>
  </ul>
Community
  <ul>
  <li id="menuwiki"><a href="http://wiki.txt2tags.org">Wiki</a></li>
  <li id="menublog"><a href="http://txt2tags.wordpress.com">Blog</a></li>
  <li id="menuteam"><a href="./team/index.html">The Team</a></li>
  <li id="menuchildren"><a href="./children.html">The Children</a></li>
  <li id="menucomments"><a href="http://txt2tags.wordpress.com/user-comments/">User Comments</a></li>
  <li id="menuart"><a href="./art.html">Artwork</a></li>
  </ul>
Social
  <ul>
  <li id="menuml"><a href="./ml.html">Mailing List</a></li>
  <li><a href="http://www.facebook.com/pages/txt2tags/335201827209">Facebook</a></li>
  <li><a href="http://twitter.com/aureliojargas">twitter</a></li>
  <!-- <li><a href="http://www.orkut.com.br/Main#Community?cmm=87935">Orkut</a></li> -->
  <li><a href="http://identi.ca/group/txt2tags">identi.ca</a></li>
  </ul>

<P>
<A HREF="https://www.paypal.com/cgi-bin/webscr?cmd=_xclick&amp;business=verde%40aurelio%2enet&amp;item_name=txt2tags%20donation&amp;no_shipping=1&amp;return=http%3a%2f%2faurelio%2enet%2fdonate%2dthanks%2ehtml&amp;cn=&amp;tax=0&amp;currency_code=USD&amp;bn=PP%2dDonationsBF&amp;charset=UTF%2d8"><IMG ALIGN="middle" SRC="img/donate.png" BORDER="0" alt="DONATE"></A>
</P>
</div>

<H2>Yes, YOU can make it</H2>

<P>
So you like txt2tags very much but your favorite format is not yet supported? How about adding it yourself?
</P>
<P>
You don't need to be a Python programmer to do it. You'll just define variables, no algorithm is needed. In fact, if text editors and the command line don't scare you, <B>you don't even need to be a programmer</B> to do it. Just read this document carefully :)
</P>
<P>
On the following guidelines we'll add the imaginary "foo" target to txt2tags.
</P>
<DIV CLASS="toc">

  <UL>
  <LI><A HREF="#toc1">1. Get the most recent txt2tags source code</A>
  <LI><A HREF="#toc2">2. Add the target identifier and description in TARGET_NAMES</A>
  <LI><A HREF="#toc3">3. Add the header template in HEADER_TEMPLATE</A>
  <LI><A HREF="#toc4">4. Add the target's tags in getTags()</A>
  <LI><A HREF="#toc5">5. Add the target's rules in getRules()</A>
  <LI><A HREF="#toc6">6. Send me your work!</A>
  <LI><A HREF="#toc7">A real-world example</A>
  <LI><A HREF="#toc8">Another real-world example</A>
  </UL>

</DIV>

<H1 ID="toc1">1. Get the most recent txt2tags source code</H1>

<P>
IMPORTANT!
</P>
<P>
Before you start, make sure you have the newest txt2tags code, available at <A HREF="http://txt2tags.googlecode.com/svn/trunk/txt2tags">http://txt2tags.googlecode.com/svn/trunk/txt2tags</A>
</P>
<P>
Open this file on your favorite text editor.
</P>

<H1 ID="toc2">2. Add the target identifier and description in TARGET_NAMES</H1>

<P>
At the beginning of the txt2tags source code, right after the long heading comments, you'll find the declaration of all the available targets:
</P>

<PRE>
TARGET_NAMES = {
  'html' : _('HTML page'),
  'xhtml': _('XHTML page'),
  'sgml' : _('SGML document'),
  'tex'  : _('LaTeX document'),
  'lout' : _('Lout document'),
  'man'  : _('UNIX Manual page'),
  'mgp'  : _('MagicPoint presentation'),
  'wiki' : _('Wikipedia page'),
  'gwiki': _('Google Wiki page'),
  'doku' : _('DokuWiki page'),
  'moin' : _('MoinMoin page'),
  'pm6'  : _('PageMaker document'),
  'txt'  : _('Plain Text'),
  <b>'foo'  : _('FOO Document'),</b>
}
</PRE>

<P>
Add a new item to the dictionary, choosing an identifier and a textual description for your new target.
</P>
<P>
Notes:
</P>

<UL>
<LI>Copy &amp; paste instead writing from zero to make sure you won't forgot the _(...) format.
<LI>Choose a short name for the identifier (5 letters or less).
<LI>The identifier will also be the filename extension used by txt2tags when saving the result to a file.
</UL>

<P>
You can already run <CODE>./txt2tags --targets</CODE> and see your new target listed!
</P>

<H1 ID="toc3">3. Add the header template in HEADER_TEMPLATE</H1>

<P>
The headers are the first three lines of a txt2tags document. Some targets as LaTeX have a specific place for them (the Preamble), others don't. Make a decision on how to format the header lines. You have three tokens available:
</P>

<UL>
<LI><B>%(HEADER1)s</B> - The first source line (Document title)
<LI><B>%(HEADER2)s</B> - The second source line (Document author)
<LI><B>%(HEADER3)s</B> - The third source line (Document date)
</UL>

<P>
The title/author/date contents are just suggestions. The user can put whatever he/she wants at those lines. And remember that while the first line (title) is required, the other two are optional. Their lines at this template will be removed if not present.
</P>

<PRE>
  '<b>foo</b>': """\
<b>&lt;title-tag&gt;</b>%(HEADER1)s<b>&lt;/title-tag&gt;</b>

<b>&lt;author-tag&gt;</b>%(HEADER2)s<b>&lt;/author-tag&gt;</b>

<b>&lt;date-tag&gt;</b>%(HEADER3)s<b>&lt;date-tag&gt;</b>
""",
</PRE>

	<BLOCKQUOTE>
	Tip: Once again, copy &amp; paste instead writing from zero.
	</BLOCKQUOTE>
	<BLOCKQUOTE>
	Tip: To show a literal "%" use "%%".
	</BLOCKQUOTE>

<H1 ID="toc4">4. Add the target's tags in getTags()</H1>

<P>
This is the most tricky step. Some targets are easy, some are more exotic.
</P>
<P>
First, find the definition of the getTags() function.
</P>

<PRE>
def getTags(config):
</PRE>

<P>
The <B>keys</B> variable stores all the valid tokens you can use to describe your target's tags.
</P>
<P>
The <B>alltags</B> dictionary stores the tags for each target. This is where you'll add your new target.
</P>

<PRE>
'<b>foo</b>': {
   'title1'              : '<b>&lt;title-tag-1&gt;</b>\a<b>&lt;/title-tag-1&gt;</b>' ,
   'title2'              : '<b>&lt;title-tag-2&gt;</b>\a<b>&lt;/title-tag-2&gt;</b>' ,
   'title3'              : '<b>&lt;title-tag-3&gt;</b>\a<b>&lt;/title-tag-3&gt;</b>' ,
   ...
},
</PRE>

<P>
<B>IMPORTANT:</B> The easiest is to find an already added target that is similar to yours, copy &amp; paste the code and modify it. <B>Don't start from zero.</B>
</P>
<P>
Note the <CODE>\a</CODE> on the tags. It represents the text the user typed inside that mark. So <CODE>=My Title=</CODE> will be converted to <CODE>&lt;title-tag-1&gt;My Title&lt;/title-tag-1&gt;</CODE>.
</P>
<P>
You can also put a <CODE>\n</CODE> character to represent a line break. It's useful if your tag spans in multiple lines. A Tab can be inserted using <CODE>\t</CODE>.
</P>
<P>
At this point you can already run a <CODE>txt2tags -t foo sample.t2t</CODE> command and it will work! The results will be saved to sample.foo. Check it out.
</P>
	<BLOCKQUOTE>
	Tip: Keep editing and running to adjust and improve your target support.
	</BLOCKQUOTE>

<H1 ID="toc5">5. Add the target's rules in getRules()</H1>

<P>
This is the final step. Besides the tags already added, now you can also specify some rules to fine-tune your target code.
</P>
<P>
Search for the function definition:
</P>

<PRE>
def getRules(config):
</PRE>

<P>
Then read carefully the <B>allrules</B> comments to learn which options are available.
</P>
<P>
Once again, copy &amp; paste the entry of an already added target to make your life easier. Put there all the rules you need, always using 1 as the value. You don't need to turn off a rule with zero. Just don't mention it and it will be disabled by default. In other words, just add the rules you want to be ON.
</P>

<PRE>
'<b>foo</b>' : {
  'indentverbblock':1,
  'spacedlistitem':1,
  'parainsidelist':1,
  'keeplistindent':1,
  'barinsidequote':1,
  'autotocwithbars':1,
  'blankendmotherlist':1,
  },
</PRE>

<P>
And that's it! Now your target is fully added to the txt2tags program!
</P>
<P>
Tips:
</P>

<UL>
<LI>If in your target the <CODE>urlMark</CODE> order is reversed (label comes before the link) use the following rule: <CODE>'labelbeforelink':1</CODE>. See how this change was made in <A HREF="http://code.google.com/p/txt2tags/source/detail?r=450">r450</A>.
<P></P>
<LI>If in your target the nested lists are defined by the number of <CODE>*</CODE>, for example <CODE>**</CODE> for sublists and <CODE>***</CODE> for subsublists, use <CODE>listItemLine</CODE> instead <CODE>listItemOpen</CODE>, remove the <CODE>keeplistindent</CODE> setting and turn on <CODE>spacedlistitemopen</CODE>. See how this change was made in <A HREF="http://code.google.com/p/txt2tags/source/detail?r=181">r181</A>. Example:

<PRE>
# getTags
'listItemOpen': '* ',                     * mother list
                                ====&gt;       * sub list
# getRules                                    * sub sub list
'keeplistindent':1,

<span style="font-weight:bold;color:red">--------------------------------------------------------------</span>

# getTags
'listItemLine': '*',                      * mother list
                                ====&gt;     ** sub list
# getRules                                *** sub sub list
'spacedlistitemopen':1,
</PRE>

</UL>

<H1 ID="toc6">6. Send me your work!</H1>

<P>
Once you're done, <A HREF="http://aurelio.net/img/emeio.png">send me your work</A> so I can include it on the official txt2tags source and everybody can use your target. You will also be included on the <A HREF="team">Team page</A> and your karma will increase in 2,715 points :)
</P>
<P>
The only file you must e-mail me is the full txt2tags code modified with your target.
</P>
<P>
<B>Have a good programming time!</B>
</P>

<H1 ID="toc7">A real-world example</H1>

<P>
See how easy it was to add the DokuWiki target to txt2tags. This file is in the diff format, where red lines are OLD and green lines are NEW:
</P>

<PRE>
<span style="font-weight:bold;color:red">--- txt2tags	2007-11-08 15:10:58.000000000 -0200</span>
<span style="font-weight:bold;color:green">+++ txt2tags-doku	2007-11-11 23:09:11.000000000 -0200</span>
@@ -175,6 +175,7 @@
   'mgp'  : _('MagicPoint presentation'),
   'wiki' : _('Wikipedia page'),
   'gwiki': _('Google Wiki page'),
<span style="font-weight:bold;color:green">+  'doku' : _('DokuWiki page'),</span>
   'moin' : _('MoinMoin page'),
   'pm6'  : _('PageMaker document'),
   'txt'  : _('Plain Text'),
@@ -438,6 +439,14 @@
 
 """,
 
<span style="font-weight:bold;color:green">+  'doku': """\</span>
<span style="font-weight:bold;color:green">+===== %(HEADER1)s =====</span>
<span style="font-weight:bold;color:green">+</span>
<span style="font-weight:bold;color:green">+**//%(HEADER2)s//**</span>
<span style="font-weight:bold;color:green">+</span>
<span style="font-weight:bold;color:green">+//%(HEADER3)s//</span>
<span style="font-weight:bold;color:green">+""",</span>
<span style="font-weight:bold;color:green">+</span>
   'wiki': """\
 '''%(HEADER1)s'''
 
@@ -895,6 +905,52 @@
 	   'tableCellSep'        : ' || '          ,
 	},
 
<span style="font-weight:bold;color:green">+	# http://wiki.splitbrain.org/wiki:syntax</span>
<span style="font-weight:bold;color:green">+	# Hint: &lt;br&gt; is \\ $</span>
<span style="font-weight:bold;color:green">+	# Hint: You can add footnotes ((This is a footnote))</span>
<span style="font-weight:bold;color:green">+	'doku': {</span>
<span style="font-weight:bold;color:green">+	   'title1'              : '===== \a =====',</span>
<span style="font-weight:bold;color:green">+	   'title2'              : '==== \a ===='  ,</span>
<span style="font-weight:bold;color:green">+	   'title3'              : '=== \a ==='    ,</span>
<span style="font-weight:bold;color:green">+	   'title4'              : '== \a =='      ,</span>
<span style="font-weight:bold;color:green">+	   'title5'              : '= \a ='        ,</span>
<span style="font-weight:bold;color:green">+	   # DokuWiki uses '  ' identation to mark verb blocks (see indentverbblock)</span>
<span style="font-weight:bold;color:green">+	   'blockQuoteLine'      : '&gt;'             ,</span>
<span style="font-weight:bold;color:green">+	   'fontMonoOpen'        : "''"            ,</span>
<span style="font-weight:bold;color:green">+	   'fontMonoClose'       : "''"            ,</span>
<span style="font-weight:bold;color:green">+	   'fontBoldOpen'        : "**"            ,</span>
<span style="font-weight:bold;color:green">+	   'fontBoldClose'       : "**"            ,</span>
<span style="font-weight:bold;color:green">+	   'fontItalicOpen'      : "//"            ,</span>
<span style="font-weight:bold;color:green">+	   'fontItalicClose'     : "//"            ,</span>
<span style="font-weight:bold;color:green">+	   'fontUnderlineOpen'   : "__"            ,</span>
<span style="font-weight:bold;color:green">+	   'fontUnderlineClose'  : "__"            ,</span>
<span style="font-weight:bold;color:green">+	   'fontStrikeOpen'      : '&lt;del&gt;'         ,</span>
<span style="font-weight:bold;color:green">+	   'fontStrikeClose'     : '&lt;/del&gt;'        ,</span>
<span style="font-weight:bold;color:green">+	   'listItemOpen'        : '  * '          ,</span>
<span style="font-weight:bold;color:green">+	   'numlistItemOpen'     : '  - '          ,</span>
<span style="font-weight:bold;color:green">+	   'bar1'                : '----'          ,</span>
<span style="font-weight:bold;color:green">+	   'url'                 : '[[\a]]'        ,</span>
<span style="font-weight:bold;color:green">+	   'urlMark'             : '[[\a|\a]]'     ,</span>
<span style="font-weight:bold;color:green">+	   'email'               : '[[\a]]'        ,</span>
<span style="font-weight:bold;color:green">+	   'emailMark'           : '[[\a|\a]]'     ,</span>
<span style="font-weight:bold;color:green">+	   'img'                 : '{{\a}}'        ,</span>
<span style="font-weight:bold;color:green">+	   'imgAlignLeft'        : '{{\a }}'       ,</span>
<span style="font-weight:bold;color:green">+	   'imgAlignRight'       : '{{ \a}}'       ,</span>
<span style="font-weight:bold;color:green">+	   'imgAlignCenter'      : '{{ \a }}'      ,</span>
<span style="font-weight:bold;color:green">+	   'tableTitleRowOpen'   : '^ '            ,</span>
<span style="font-weight:bold;color:green">+	   'tableTitleRowClose'  : ' ^'            ,</span>
<span style="font-weight:bold;color:green">+	   'tableTitleCellSep'   : ' ^ '           ,</span>
<span style="font-weight:bold;color:green">+	   'tableRowOpen'        : '| '            ,</span>
<span style="font-weight:bold;color:green">+	   'tableRowClose'       : ' |'            ,</span>
<span style="font-weight:bold;color:green">+	   'tableCellSep'        : ' | '           ,</span>
<span style="font-weight:bold;color:green">+# DokuWiki has no attributes. The content must be aligned!</span>
<span style="font-weight:bold;color:green">+#	   '_tableCellAlignRight' : '&lt;)&gt;'           , # ??</span>
<span style="font-weight:bold;color:green">+#	   '_tableCellAlignCenter': '&lt;:&gt;'           , # ??</span>
<span style="font-weight:bold;color:green">+# DokuWiki colspan is the same as txt2tags' with multiple |||</span>
<span style="font-weight:bold;color:green">+	   # 'comment'             : '## \a'         , # ??</span>
<span style="font-weight:bold;color:green">+	   # TOC is automatic</span>
<span style="font-weight:bold;color:green">+	},</span>
<span style="font-weight:bold;color:green">+	</span>
 	# http://en.wikipedia.org/wiki/Help:Editing
 	'wiki': {
 	   'title1'              : '== \a =='        ,
@@ -1266,8 +1323,23 @@
	    'autonumberlist':1,
 	    'breaktitleopen':1,
 	    },
<span style="font-weight:bold;color:green">+	  'doku': {</span>
<span style="font-weight:bold;color:green">+	    'indentverbblock':1,           # DokuWiki uses '  ' to mark verb blocks</span>
<span style="font-weight:bold;color:green">+	    'spacedlistitem':1,</span>
<span style="font-weight:bold;color:green">+	    'linkable':1,</span>
<span style="font-weight:bold;color:green">+	    'blankendmotherlist':1,</span>
<span style="font-weight:bold;color:green">+	    'keeplistindent':1,</span>
<span style="font-weight:bold;color:green">+	    'tableable':1,</span>
<span style="font-weight:bold;color:green">+	    'barinsidequote':1,</span>
<span style="font-weight:bold;color:green">+	    'blankendtable':1,</span>
<span style="font-weight:bold;color:green">+	    'tablecellstrip':1,</span>
<span style="font-weight:bold;color:green">+	    'autotocwithbars':1,</span>
<span style="font-weight:bold;color:green">+	    'autonumberlist':1,</span>
<span style="font-weight:bold;color:green">+	    'imgalignable':1,</span>
<span style="font-weight:bold;color:green">+	    'tablecellaligntype':'cell',</span>
<span style="font-weight:bold;color:green">+	    },	</span>
 	  'wiki': {
 	    'linkable':1,
 	    'blankendmotherlist':1,
</PRE>

<H1 ID="toc8">Another real-world example</H1>

<P>
Directly from the txt2tags SVN, see how easy the BBCode target was added:
</P>
<P>
<A HREF="http://code.google.com/p/txt2tags/source/detail?r=410">http://code.google.com/p/txt2tags/source/detail?r=410</A>
</P>
<P>
Click in "expand all" to see the code. The green part is the new code.
</P>
</div><div id="footer">
<P>
<IMG ALIGN="middle" SRC="img/t2tpowered-white.png" BORDER="0" ALT="">
</P>
<a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-sa/3.0/80x15.png"></a>
<P>
Last modified on 11 January 2012 at 17:30
(<A HREF="new-target.t2t">See sources</A>,
<A HREF="http://validator.w3.org/check?uri=referer">Validate HTML</A>)
</P>
</div><div id="fake">
<!-- Google Analytics code -->
<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-280222-14']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

</script>
</DIV>

<!-- html code generated by txt2tags 2.6.641 (http://txt2tags.org) -->
<!-- cmdline: txt2tags -t html ./new-target.t2t -->
</BODY></HTML>
